如果有幸接手他人的程式碼，有可能會發生以下幾種情況，

• 基本上不存在 IDE 自行產生的註解以外的註解。
• 滿滿的註解起來的程式碼，但是這些註解，都是不知道還有沒有用途
• 完全不明白意思的註解

沒有註解的程式碼

假若該程式碼，具有高閱讀性，沒有註解，其實沒有那麼重要。但是，如果程式內容本身不易閱讀，為了未來的自己，或是接收程式的後人，請養成註解的習慣。

無用的註解

public int StatisticCostAmount(...)
{
    ...
    // 解法二
    foreach(var item in items)
    {
        ...
       
           
        // 2017/5/12 修改
        ...        
    }
    // Console.WriteLine($"total={total}")
}

開發的過程中，有時候，為了 DEBUG，可能會在程式碼中，插入除入用的程式碼。像上面範例中出現的 Console.WriteLine(...)，基本上，在完成除錯後，應該要刪除這些有特定用途的程式碼。

食之無味、棄之可惜的註解

public int StatisticCostAmount(...)
{
    ...
    // 做法一
    // .....
    // .....
    
    // 做法二
    foreach(var item in items)
    {
        ...        
    }
}

這種情況可能發生在接收過來的程式碼，或是為了效能改寫原本正常運行的的程式寫法。改寫完成後，想保留本來的寫法，以便以後可以回來查詢的機會。

事實上，如果修改後的程式沒有發生任何問題，回來查看被註解掉的程式碼機會，基本上無限趨近於 0。
實務上，在修改前，應該就要將原本的程式碼上傳至版控軟體中，進行任何的功能變動時，應養成上版控的習慣。

保留註解程式碼的原因，是為了回朔當初的寫法或功能，請愛用版控軟體，保持程式碼的清潔，以提升閱讀性。

若是一定要保留在程式碼中，應該針對註解的部份，額外增加註解，說明保該程式碼保留下來的原因。

無法解讀的註解

public int StatisticCostAmount(...)
{
    ...    
    foreach(var item in items)
    {
        ...
        
        // 2017/5/12 修改
        ...        
    }
}

看到這句註解，應該是滿頭霧水，註解的用意是？

• 單純表示 2017/5/12 修改的?
  如果只是單純註明這段程式碼修改的日期，那這個註解本身是沒有任何意義的，應該盡可能避免。小弟看到這種註解，通常都是刪除。

• 告知協同開發的伙伴說明程式碼己經修改？
  一般而言，如果需要協同開發程式，表示軟體有一定的規模。請愛用版本控制軟體，版控軟體可以更有效的比對出異動的程式碼。
  如果工作環境還沒有版控軟體，麻煩試著自行架設，會發現新的世界。

• 修改程式碼是因為需求變動？
  如果是因為臨時性的需求變動，特別標註修改日期，那麼應該連帶說明修改的原因。以確保其他人看到這段程式碼時，第一時間可以明白修改的原因。

有益的註解

有些時候，可能某個功能的實作是因為特定因素，所以採用特定的做法，這時，就可以特別註明，讓後面的人知道，避免在維護程式時，將功能改壞。

回顧

軟體開發過程中，為了修改程式邏輯，經常會出現將原本的程式碼區段註解，避免之後還有派上用場旳時間。但是在完成開發後，整理程式碼時，應該清除將這些暫時註解掉的程式碼。

若程式碼己經具有高閱讀性，某方面而言，是可以替代一定程度的註解。但是註解可沒有那麼單純。註解中，有時候，會特別記錄重要的資訊，而這些資訊，正好是程式碼本身無法表示出來的。

在 Clean Code 一書中，關於註解的章節中，提到好的程式碼，應該程式碼本身就是最好的註解，雖然無法避免使用註解進行說明，但應該該竭盡所能，讓註解減少到最低。對於這個說法，很多人抱持的不同看法，算是滿有爭議的說法。但也很值得我們去思考的這個問題。

推薦

書藉

1. Robert C. Martin, Clean Code 無瑕的程式碼

相關文章推薦

• 『用註解補足程式碼易讀性？』 -- 論註解的是與非